Error reporting improvements by novalisdenahi · Pull Request #82 · configcat/android-sdk

novalisdenahi · 2026-07-15T16:26:33Z

Describe the purpose of your pull request

Added EvaluationErrorCode and RefreshErrorCode and exposed them through the EvaluationDetails and RefreshResult.

Related issues (only if applicable)

Trello ticket

How to test? (only if applicable)

What part of the application was affected by the changes? What should be tested?

Security (only if applicable)

Describe any potential risks that could affect the component in terms of security.

Requirement checklist (only if applicable)

I have covered the applied changes with automated tests.
I have executed the full automated test set against my changes.
I have validated my changes against all supported platform versions.
I have read and accepted the contribution agreement.

…r codes

…d RefreshResult.

….12.0

sonarqubecloud · 2026-07-17T14:06:02Z

Quality Gate failed

Failed conditions
75.2% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

adams85 · 2026-07-29T08:20:31Z

+    /**
+     * The error code of the evaluation result. If the evaluation was successful, this will be EvaluationErrorCode.NONE.
+     */
+    public EvaluationErrorCode getErrorCode() {
+        return errorCode;
+    }
+
+    /**
+     * The error exception object related to the error. If the evaluation was successful, this will be null.
+     */


I suggest using the already UX-approved texts for documentation .

Suggested change

/**

* The error code of the evaluation result. If the evaluation was successful, this will be EvaluationErrorCode.NONE.

*/

public EvaluationErrorCode getErrorCode() {

return errorCode;

}

/**

* The error exception object related to the error. If the evaluation was successful, this will be null.

*/

/**

* The code identifying the reason for the error in case the operation failed. (If the evaluation was successful, this will be EvaluationErrorCode.NONE.)

*/

public EvaluationErrorCode getErrorCode() {

return errorCode;

}

/**

* The exception object related to the error in case the operation failed. (If the evaluation was successful, this will be null.)

*/

adams85 · 2026-07-29T08:25:22Z

+
+    public RefreshErrorCode errorCode() {
+        return errorCode;
+    }
+
+    public Throwable errorException() {
+        return errorException;
+    }


Would be nice to add documentation here too. E.g.: https://github.com/configcat/.net-sdk/blob/v10.0.0/src/ConfigCatClient/RefreshResult.cs#L60-L73

adams85 · 2026-07-29T08:26:36Z

+    NONE(0),
+
+    /**
+     * The refresh operation failed because the client is configured to use the `OverrideBehaviour.LocalOnly`


Suggested change

* The refresh operation failed because the client is configured to use the `OverrideBehaviour.LocalOnly`

* The refresh operation failed because the client is configured to use the `OverrideBehaviour.LOCAL_ONLY`

adams85 · 2026-07-29T08:49:40Z

+    static <T> Result<T, RefreshErrorCode> success(T value) {
+        return new Result<>(value, null, RefreshErrorCode.NONE, null);
    }

-    static <T> Result<T> success(T value) {
-        return new Result<>(value, null);
+    static <T, E extends ErrorCode> Result<T, E> success(T value, E errorCode) {
+        return new Result<>(value, null, errorCode, null);
    }


It doesn't seem to be a good API design to introduce a factory method only for a specific case in a general class like this. It's also error-prone because naming doesn't make this clear to maintainers. They won't know unless reading the method definition.

Suggested change

static <T> Result<T, RefreshErrorCode> success(T value) {

return new Result<>(value, null, RefreshErrorCode.NONE, null);

}

static <T> Result<T> success(T value) {

return new Result<>(value, null);

static <T, E extends ErrorCode> Result<T, E> success(T value, E errorCode) {

return new Result<>(value, null, errorCode, null);

}

static <T, E extends ErrorCode> Result<T, E> success(T value, E errorCode) {

return new Result<>(value, null, errorCode, null);

}

Alternatively, we might replace the success methods with something like refreshSuccess and evaluationSuccess. However, this is my less preferred option.

adams85 · 2026-07-29T08:56:11Z

+    /** The refresh operation failed because an invalid HTTP response was received (200 OK with an invalid content). */
+    INVALID_HTTP_RESPONSE_CONTENT(1105),
+
+    /** Initialization of the SDK timed out. **/


Suggested change

/** Initialization of the SDK timed out. **/

/** Client initialization could not complete within `maxInitWaitTimeSeconds`. **/

adams85 · 2026-07-29T09:41:01Z

    private static <T> void validateReturnType(Class<T> classOfT) {
        if (!(classOfT == String.class || classOfT == Integer.class || classOfT == int.class || classOfT == Double.class || classOfT == double.class || classOfT == Boolean.class || classOfT == boolean.class)) {
-            throw new IllegalArgumentException("Only String, Integer, Double or Boolean types are supported.");
+            throw new EvaluationException("Only String, Integer, Double or Boolean types are supported.");


This should remain an exception thrown early instead of being swallowed to be consistent with other SDKs. E.g.: https://github.com/configcat/.net-sdk/blob/v10.0.0/src/ConfigCatClient/Extensions/TypeExtensions.cs#L11

Suggested change

throw new EvaluationException("Only String, Integer, Double or Boolean types are supported.");

throw new IllegalArgumentException("Only String, Integer, Double or Boolean types are supported.");

adams85 · 2026-07-29T09:53:03Z

+        try {
+            validateReturnType(classOfT);

-        return this.getSettingsAsync()
+            return this.getSettingsAsync()
                .thenApply(settingsResult -> {
-                    Result<Setting> checkSettingResult = checkSettingAvailable(settingsResult, key, defaultValue);
+                    Result<Setting, EvaluationErrorCode> checkSettingResult = checkSettingAvailable(settingsResult, key, defaultValue);
                    if (checkSettingResult.error() != null) {
-                        EvaluationDetails<Object> evaluationDetails = EvaluationDetails.fromError(key, defaultValue, checkSettingResult.error(), user);
+                        EvaluationDetails<Object> evaluationDetails = EvaluationDetails.fromError(key, defaultValue, checkSettingResult.errorCode(), checkSettingResult.error(), null, user);
                        this.hooks.invokeOnFlagEvaluated(evaluationDetails);
                        return evaluationDetails.asTypeSpecific();
                    }
                    return this.evaluate(classOfT, checkSettingResult.value(),
                            key, user != null ? user : this.defaultUser, settingsResult.fetchTime(), settingsResult.settings());
                });
+        } catch (InvalidConfigModelException e) {
+            this.logger.error(1002, ConfigCatLogMessages.getSettingEvaluationErrorWithDefaultValue("getValueDetails", key, "defaultValue", defaultValue), e);
+            return CompletableFuture.completedFuture(EvaluationDetails.fromError(key, defaultValue, EvaluationErrorCode.INVALID_CONFIG_MODEL, e.getMessage(), null, user));
+        } catch (EvaluationException e) {
+            this.logger.error(1002, ConfigCatLogMessages.getSettingEvaluationErrorWithDefaultValue("getValueDetails", key, "defaultValue", defaultValue), e);
+            return CompletableFuture.completedFuture(EvaluationDetails.fromError(key, defaultValue, EvaluationErrorCode.SETTING_VALUE_TYPE_MISMATCH, e.getMessage(),null, user));
+        } catch (Exception e) {
+            this.logger.error(1002, ConfigCatLogMessages.getSettingEvaluationErrorWithDefaultValue("getValueDetails", key, "defaultValue", defaultValue), e);
+            return CompletableFuture.completedFuture(EvaluationDetails.fromError(key, defaultValue, EvaluationErrorCode.UNEXPECTED_ERROR, e.getMessage(), e, user));
+        }


There are multiple issues with this change:

The exception thrown by validateReturnType(classOfT); shouldn't be swallowed. (It should remain an early error.)

Wrapping the code that composes the completable future object won't catch exceptions thrown in the continuation callback scheduled by thenApply.

Separately handling the various types of exceptions is redundant. This can be greatly simplified using a helper method. E.g.: https://github.com/configcat/.net-sdk/blob/v10.0.0/src/ConfigCatClient/Evaluation/EvaluationHelper.cs#L182-L190

invokeOnFlagEvaluated should also be called in case of error.

The correct error handling would be something like this:

Suggested change

try {

validateReturnType(classOfT);

return this.getSettingsAsync()

return this.getSettingsAsync()

.thenApply(settingsResult -> {

Result<Setting> checkSettingResult = checkSettingAvailable(settingsResult, key, defaultValue);

Result<Setting, EvaluationErrorCode> checkSettingResult = checkSettingAvailable(settingsResult, key, defaultValue);

if (checkSettingResult.error() != null) {

EvaluationDetails<Object> evaluationDetails = EvaluationDetails.fromError(key, defaultValue, checkSettingResult.error(), user);

EvaluationDetails<Object> evaluationDetails = EvaluationDetails.fromError(key, defaultValue, checkSettingResult.errorCode(), checkSettingResult.error(), null, user);

this.hooks.invokeOnFlagEvaluated(evaluationDetails);

return evaluationDetails.asTypeSpecific();

}

return this.evaluate(classOfT, checkSettingResult.value(),

key, user != null ? user : this.defaultUser, settingsResult.fetchTime(), settingsResult.settings());

});

} catch (InvalidConfigModelException e) {

this.logger.error(1002, ConfigCatLogMessages.getSettingEvaluationErrorWithDefaultValue("getValueDetails", key, "defaultValue", defaultValue), e);

return CompletableFuture.completedFuture(EvaluationDetails.fromError(key, defaultValue, EvaluationErrorCode.INVALID_CONFIG_MODEL, e.getMessage(), null, user));

} catch (EvaluationException e) {

this.logger.error(1002, ConfigCatLogMessages.getSettingEvaluationErrorWithDefaultValue("getValueDetails", key, "defaultValue", defaultValue), e);

return CompletableFuture.completedFuture(EvaluationDetails.fromError(key, defaultValue, EvaluationErrorCode.SETTING_VALUE_TYPE_MISMATCH, e.getMessage(),null, user));

} catch (Exception e) {

this.logger.error(1002, ConfigCatLogMessages.getSettingEvaluationErrorWithDefaultValue("getValueDetails", key, "defaultValue", defaultValue), e);

return CompletableFuture.completedFuture(EvaluationDetails.fromError(key, defaultValue, EvaluationErrorCode.UNEXPECTED_ERROR, e.getMessage(), e, user));

}

validateReturnType(classOfT);

return this.getSettingsAsync()

.thenApply(settingsResult -> {

Result<Setting, EvaluationErrorCode> checkSettingResult = checkSettingAvailable(settingsResult, key, defaultValue);

if (checkSettingResult.error() != null) {

EvaluationDetails<Object> evaluationDetails = EvaluationDetails.fromError(key, defaultValue, checkSettingResult.errorCode(), checkSettingResult.error(), null, user);

this.hooks.invokeOnFlagEvaluated(evaluationDetails);

return evaluationDetails.asTypeSpecific();

}

try {

return this.evaluate(classOfT, checkSettingResult.value(),

key, user != null ? user : this.defaultUser, settingsResult.fetchTime(), settingsResult.settings());

} catch (Exception e) {

this.logger.error(1002, ConfigCatLogMessages.getSettingEvaluationErrorWithDefaultValue("getValueDetails", key, "defaultValue", defaultValue), e);

EvaluationDetails<Object> evaluationDetails = EvaluationDetails.fromError(key, defaultValue, getEvaluationErrorCode(e), e.getMessage(), e, user);

this.hooks.invokeOnFlagEvaluated(evaluationDetails);

return evaluationDetails.asTypeSpecific();

}

});

adams85 · 2026-07-29T10:06:07Z

        try {
            return forceRefreshAsync().get();
        } catch (InterruptedException e) {
            logger.error(0, "Thread interrupted.", e);
            Thread.currentThread().interrupt();
        } catch (Exception e) {
            this.logger.error(1003, ConfigCatLogMessages.getForceRefreshError("forceRefresh"), e);
        }
-        return new RefreshResult(false, "An error occurred during the refresh.");
+        return new RefreshResult(false, "An error occurred during the refresh.", RefreshErrorCode.UNEXPECTED_ERROR, null);


Let's include the exception in the result object following the pattern used in e.g. getValueDetails.

adams85 · 2026-07-29T10:15:48Z

+            this.hooks.invokeOnFlagEvaluated(EvaluationDetails.fromError(key, defaultValue, EvaluationErrorCode.UNEXPECTED_ERROR, error + " " + e.getMessage(), e, userObject));
            this.logger.error(2001, error, e);


This method should also handle the specific error cases (EvaluationException, InvalidConfigModelException).

Also, we should log the error first, as invokeOnFlagEvaluated calls user-provided code that might throw.

Suggested change

this.hooks.invokeOnFlagEvaluated(EvaluationDetails.fromError(key, defaultValue, EvaluationErrorCode.UNEXPECTED_ERROR, error + " " + e.getMessage(), e, userObject));

this.logger.error(2001, error, e);

this.logger.error(2001, error, e);

this.hooks.invokeOnFlagEvaluated(EvaluationDetails.fromError(key, defaultValue, getEvaluationErrorCode(e), error + " " + e.getMessage(), e, userObject));

adams85 · 2026-07-29T10:17:39Z

            return double.class;
        else
-            throw new IllegalArgumentException("Only String, Integer, Double or Boolean types are supported");
+            throw new EvaluationException("Only String, Integer, Double or Boolean types are supported");


Suggested change

throw new EvaluationException("Only String, Integer, Double or Boolean types are supported");

throw new IllegalArgumentException("Only String, Integer, Double or Boolean types are supported.");

adams85 · 2026-07-29T10:24:57Z

            FormattableLogMessage message = ConfigCatLogMessages.getFetchReceived200WithInvalidBodyError(cfRayId);
            this.logger.error(1105, message, e);
-            return Result.error(message, null);
+            return Result.error(message, null, EvaluationErrorCode.INVALID_CONFIG_MODEL, null);


Let's keep it consistent with other SDKs. E.g.: https://github.com/configcat/.net-sdk/blob/v10.0.0/src/ConfigCatClient/ConfigService/DefaultConfigFetcher.cs#L73

Suggested change

return Result.error(message, null, EvaluationErrorCode.INVALID_CONFIG_MODEL, null);

return Result.error(message, null, EvaluationErrorCode.INVALID_HTTP_RESPONSE_CONTENT, null);

novalisdenahi added 4 commits June 12, 2026 15:35

WIP Enhance error reporting with detailed evaluation and refresh erro…

c519ae6

…r codes

WIP Enhance error reporting with detailed evaluation and refresh erro…

d9aa2fd

…r codes

Fix test

916274e

Enhance test assertions for offline scenarios

bacb715

novalisdenahi requested a review from a team as a code owner July 15, 2026 16:26

novalisdenahi added 3 commits July 16, 2026 15:22

Add the exception object related to the error to EvaluationDetails an…

c1e0bfd

…d RefreshResult.

Update tests and add missing getErrorException to EvaluationDetails

7bf5812

Update Gradle to 8.9, android-gradle to 8.2.0 and mockito-inline to 5…

67ec576

….12.0

adams85 reviewed Jul 29, 2026

View reviewed changes

adams85 requested changes Jul 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Error reporting improvements - #82

Error reporting improvements#82
novalisdenahi wants to merge 7 commits into
masterfrom
error-reporting-improvements

novalisdenahi commented Jul 15, 2026

Uh oh!

sonarqubecloud Bot commented Jul 17, 2026

Uh oh!

adams85 Jul 29, 2026

Uh oh!

adams85 Jul 29, 2026

Uh oh!

adams85 Jul 29, 2026

Uh oh!

adams85 Jul 29, 2026 •

edited

Loading

Uh oh!

adams85 Jul 29, 2026

Uh oh!

adams85 Jul 29, 2026 •

edited

Loading

Uh oh!

adams85 Jul 29, 2026 •

edited

Loading

Uh oh!

adams85 Jul 29, 2026

Uh oh!

adams85 Jul 29, 2026

Uh oh!

adams85 Jul 29, 2026 •

edited

Loading

Uh oh!

adams85 Jul 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	* The refresh operation failed because the client is configured to use the `OverrideBehaviour.LocalOnly`
	* The refresh operation failed because the client is configured to use the `OverrideBehaviour.LOCAL_ONLY`

	/ Initialization of the SDK timed out. /
	/ Client initialization could not complete within `maxInitWaitTimeSeconds`. /

	throw new EvaluationException("Only String, Integer, Double or Boolean types are supported.");
	throw new IllegalArgumentException("Only String, Integer, Double or Boolean types are supported.");

		this.hooks.invokeOnFlagEvaluated(EvaluationDetails.fromError(key, defaultValue, EvaluationErrorCode.UNEXPECTED_ERROR, error + " " + e.getMessage(), e, userObject));
		this.logger.error(2001, error, e);

	return Result.error(message, null, EvaluationErrorCode.INVALID_CONFIG_MODEL, null);
	return Result.error(message, null, EvaluationErrorCode.INVALID_HTTP_RESPONSE_CONTENT, null);

Uh oh!

Conversation

novalisdenahi commented Jul 15, 2026

Describe the purpose of your pull request

Related issues (only if applicable)

How to test? (only if applicable)

Security (only if applicable)

Requirement checklist (only if applicable)

Uh oh!

sonarqubecloud Bot commented Jul 17, 2026

Quality Gate failed

Uh oh!

adams85 Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

adams85 Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

adams85 Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

adams85 Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adams85 Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

adams85 Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adams85 Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adams85 Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

adams85 Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

adams85 Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adams85 Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adams85 Jul 29, 2026 •

edited

Loading

adams85 Jul 29, 2026 •

edited

Loading

adams85 Jul 29, 2026 •

edited

Loading

adams85 Jul 29, 2026 •

edited

Loading